home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 January: Mac OS SDK / Dev.CD Jan 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / CIncludes / Threads.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  10.0 KB  |  289 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Threads.h
  3.  
  4.      Contains:    Thread Manager Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 8
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1991-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __THREADS__
  18. #define __THREADS__
  19.  
  20. #ifndef __MACTYPES__
  21. #include <MacTypes.h>
  22. #endif
  23. #ifndef __MIXEDMODE__
  24. #include <MixedMode.h>
  25. #endif
  26. #ifndef __ERRORS__
  27. #include <Errors.h>
  28. #endif
  29.  
  30.  
  31.  
  32. #if PRAGMA_ONCE
  33. #pragma once
  34. #endif
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39.  
  40. #if PRAGMA_IMPORT
  41. #pragma import on
  42. #endif
  43.  
  44. #if PRAGMA_STRUCT_ALIGN
  45.     #pragma options align=mac68k
  46. #elif PRAGMA_STRUCT_PACKPUSH
  47.     #pragma pack(push, 2)
  48. #elif PRAGMA_STRUCT_PACK
  49.     #pragma pack(2)
  50. #endif
  51.  
  52. /* Thread states */
  53. typedef unsigned short                     ThreadState;
  54.  
  55. enum {
  56.     kReadyThreadState            = 0,
  57.     kStoppedThreadState            = 1,
  58.     kRunningThreadState            = 2
  59. };
  60.  
  61. /* Error codes have been meoved to Errors.(pah) */
  62. /* Thread environment characteristics */
  63. typedef void *                            ThreadTaskRef;
  64. /* Thread characteristics */
  65. typedef unsigned long                     ThreadStyle;
  66.  
  67. enum {
  68.     kCooperativeThread            = 1L << 0,
  69.     kPreemptiveThread            = 1L << 1
  70. };
  71.  
  72. /* Thread identifiers */
  73. typedef unsigned long                     ThreadID;
  74.  
  75. enum {
  76.     kNoThreadID                    = 0,
  77.     kCurrentThreadID            = 1,
  78.     kApplicationThreadID        = 2
  79. };
  80.  
  81. /* Options when creating a thread */
  82. typedef unsigned long                     ThreadOptions;
  83.  
  84. enum {
  85.     kNewSuspend                    = (1 << 0),
  86.     kUsePremadeThread            = (1 << 1),
  87.     kCreateIfNeeded                = (1 << 2),
  88.     kFPUNotNeeded                = (1 << 3),
  89.     kExactMatchThread            = (1 << 4)
  90. };
  91.  
  92. /* Information supplied to the custom scheduler */
  93.  
  94. struct SchedulerInfoRec {
  95.     unsigned long                     InfoRecSize;
  96.     ThreadID                         CurrentThreadID;
  97.     ThreadID                         SuggestedThreadID;
  98.     ThreadID                         InterruptedCoopThreadID;
  99. };
  100. typedef struct SchedulerInfoRec            SchedulerInfoRec;
  101. typedef SchedulerInfoRec *                SchedulerInfoRecPtr;
  102.  
  103. #if TARGET_CPU_68K && TARGET_RT_MAC_CFM
  104. /*
  105.     The following UniversalProcPtrs are for CFM-68k compatiblity with
  106.     the implementation of the Thread Manager.
  107. */
  108.  
  109. typedef UniversalProcPtr                 ThreadEntryProcPtr;
  110. typedef UniversalProcPtr                 ThreadSchedulerProcPtr;
  111. typedef UniversalProcPtr                 ThreadSwitchProcPtr;
  112. typedef UniversalProcPtr                 ThreadTerminationProcPtr;
  113. typedef UniversalProcPtr                 DebuggerNewThreadProcPtr;
  114. typedef UniversalProcPtr                 DebuggerDisposeThreadProcPtr;
  115. typedef UniversalProcPtr                 DebuggerThreadSchedulerProcPtr;
  116. enum {
  117.     uppThreadEntryProcInfo = kPascalStackBased
  118.          | RESULT_SIZE(SIZE_CODE(sizeof(void*)))
  119.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(void*))),
  120.     uppThreadSchedulerProcInfo = kPascalStackBased
  121.          | RESULT_SIZE(SIZE_CODE(sizeof(ThreadID)))
  122.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(SchedulerInfoRecPtr))),
  123.     uppThreadSwitchProcInfo = kPascalStackBased
  124.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ThreadID)))
  125.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void*))),
  126.     uppThreadTerminationProcInfo = kPascalStackBased
  127.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ThreadID)))
  128.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void*))),
  129.     uppDebuggerNewThreadProcInfo = kPascalStackBased
  130.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ThreadID))),
  131.     uppDebuggerDisposeThreadProcInfo = kPascalStackBased
  132.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ThreadID))),
  133.     uppDebuggerThreadSchedulerProcInfo = kPascalStackBased
  134.          | RESULT_SIZE(SIZE_CODE(sizeof(ThreadID)))
  135.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(SchedulerInfoRecPtr)))
  136. };
  137. #define NewThreadEntryProc(userRoutine)                (ThreadEntryProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppThreadEntryProcInfo, GetCurrentArchitecture())
  138. #define NewThreadSchedulerProc(userRoutine)            (ThreadSchedulerProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppThreadSchedulerProcInfo, GetCurrentArchitecture())
  139. #define NewThreadSwitchProc(userRoutine)            (ThreadSwitchProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppThreadSwitchProcInfo, GetCurrentArchitecture())
  140. #define NewThreadTerminationProc(userRoutine)        (ThreadTerminationProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppThreadTerminationProcInfo, GetCurrentArchitecture())
  141. #define NewDebuggerNewThreadProc(userRoutine)        (DebuggerNewThreadProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebuggerNewThreadProcInfo, GetCurrentArchitecture())
  142. #define NewDebuggerDisposeThreadProc(userRoutine)    (DebuggerDisposeThreadProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebuggerDisposeThreadProcInfo, GetCurrentArchitecture())
  143. #define NewDebuggerThreadSchedulerProc(userRoutine)    (DebuggerThreadSchedulerProcPtr) NewRoutineDescriptor((ProcPtr)(userRoutine), uppDebuggerThreadSchedulerProcInfo, GetCurrentArchitecture())
  144. #else
  145. /*
  146.     The following ProcPtrs cannot be interchanged with UniversalProcPtrs because
  147.     of differences between 680x0 and PowerPC runtime architectures with regard to
  148.     the implementation of the Thread Manager.
  149.  */
  150. /* Prototype for thread's entry (main) routine */
  151. typedef void *                            voidPtr;
  152. typedef CALLBACK_API( voidPtr , ThreadEntryProcPtr )(void *threadParam);
  153. /* Prototype for custom thread scheduler routine */
  154. typedef CALLBACK_API( ThreadID , ThreadSchedulerProcPtr )(SchedulerInfoRecPtr schedulerInfo);
  155. /* Prototype for custom thread switcher routine */
  156. typedef CALLBACK_API( void , ThreadSwitchProcPtr )(ThreadID threadBeingSwitched, void *switchProcParam);
  157. /* Prototype for thread termination notification routine */
  158. typedef CALLBACK_API( void , ThreadTerminationProcPtr )(ThreadID threadTerminated, void *terminationProcParam);
  159. /* Prototype for debugger NewThread notification */
  160. typedef CALLBACK_API( void , DebuggerNewThreadProcPtr )(ThreadID threadCreated);
  161. /* Prototype for debugger DisposeThread notification */
  162. typedef CALLBACK_API( void , DebuggerDisposeThreadProcPtr )(ThreadID threadDeleted);
  163. /* Prototype for debugger schedule notification */
  164. typedef CALLBACK_API( ThreadID , DebuggerThreadSchedulerProcPtr )(SchedulerInfoRecPtr schedulerInfo);
  165. #endif  /* TARGET_CPU_68K && TARGET_RT_MAC_CFM */
  166.  
  167.  
  168. /* Thread Manager routines */
  169. EXTERN_API( OSErr )
  170. CreateThreadPool                (ThreadStyle             threadStyle,
  171.                                  short                     numToCreate,
  172.                                  Size                     stackSize)                            THREEWORDINLINE(0x303C, 0x0501, 0xABF2);
  173.  
  174. EXTERN_API( OSErr )
  175. GetFreeThreadCount                (ThreadStyle             threadStyle,
  176.                                  short *                freeCount)                            THREEWORDINLINE(0x303C, 0x0402, 0xABF2);
  177.  
  178. EXTERN_API( OSErr )
  179. GetSpecificFreeThreadCount        (ThreadStyle             threadStyle,
  180.                                  Size                     stackSize,
  181.                                  short *                freeCount)                            THREEWORDINLINE(0x303C, 0x0615, 0xABF2);
  182.  
  183. EXTERN_API( OSErr )
  184. GetDefaultThreadStackSize        (ThreadStyle             threadStyle,
  185.                                  Size *                    stackSize)                            THREEWORDINLINE(0x303C, 0x0413, 0xABF2);
  186.  
  187. EXTERN_API( OSErr )
  188. ThreadCurrentStackSpace            (ThreadID                 thread,
  189.                                  unsigned long *        freeStack)                            THREEWORDINLINE(0x303C, 0x0414, 0xABF2);
  190.  
  191. EXTERN_API( OSErr )
  192. NewThread                        (ThreadStyle             threadStyle,
  193.                                  ThreadEntryProcPtr     threadEntry,
  194.                                  void *                    threadParam,
  195.                                  Size                     stackSize,
  196.                                  ThreadOptions             options,
  197.                                  void **                threadResult,
  198.                                  ThreadID *                threadMade)                            THREEWORDINLINE(0x303C, 0x0E03, 0xABF2);
  199.  
  200. EXTERN_API( OSErr )
  201. DisposeThread                    (ThreadID                 threadToDump,
  202.                                  void *                    threadResult,
  203.                                  Boolean                 recycleThread)                        THREEWORDINLINE(0x303C, 0x0504, 0xABF2);
  204.  
  205. EXTERN_API( OSErr )
  206. YieldToThread                    (ThreadID                 suggestedThread)                    THREEWORDINLINE(0x303C, 0x0205, 0xABF2);
  207.  
  208. EXTERN_API( OSErr )
  209. YieldToAnyThread                (void)                                                        FOURWORDINLINE(0x42A7, 0x303C, 0x0205, 0xABF2);
  210.  
  211. #if TARGET_OS_MAC
  212.     #define MacGetCurrentThread GetCurrentThread
  213. #endif
  214. EXTERN_API( OSErr )
  215. MacGetCurrentThread                (ThreadID *                currentThreadID)                    THREEWORDINLINE(0x303C, 0x0206, 0xABF2);
  216.  
  217. EXTERN_API( OSErr )
  218. GetThreadState                    (ThreadID                 threadToGet,
  219.                                  ThreadState *            threadState)                        THREEWORDINLINE(0x303C, 0x0407, 0xABF2);
  220.  
  221. EXTERN_API( OSErr )
  222. SetThreadState                    (ThreadID                 threadToSet,
  223.                                  ThreadState             newState,
  224.                                  ThreadID                 suggestedThread)                    THREEWORDINLINE(0x303C, 0x0508, 0xABF2);
  225.  
  226. EXTERN_API( OSErr )
  227. SetThreadStateEndCritical        (ThreadID                 threadToSet,
  228.                                  ThreadState             newState,
  229.                                  ThreadID                 suggestedThread)                    THREEWORDINLINE(0x303C, 0x0512, 0xABF2);
  230.  
  231. EXTERN_API( OSErr )
  232. SetThreadScheduler                (ThreadSchedulerProcPtr  threadScheduler)                    THREEWORDINLINE(0x303C, 0x0209, 0xABF2);
  233.  
  234. EXTERN_API( OSErr )
  235. SetThreadSwitcher                (ThreadID                 thread,
  236.                                  ThreadSwitchProcPtr     threadSwitcher,
  237.                                  void *                    switchProcParam,
  238.                                  Boolean                 inOrOut)                            THREEWORDINLINE(0x303C, 0x070A, 0xABF2);
  239.  
  240. EXTERN_API( OSErr )
  241. SetThreadTerminator                (ThreadID                 thread,
  242.                                  ThreadTerminationProcPtr  threadTerminator,
  243.                                  void *                    terminationProcParam)                THREEWORDINLINE(0x303C, 0x0611, 0xABF2);
  244.  
  245. EXTERN_API( OSErr )
  246. ThreadBeginCritical                (void)                                                        THREEWORDINLINE(0x303C, 0x000B, 0xABF2);
  247.  
  248. EXTERN_API( OSErr )
  249. ThreadEndCritical                (void)                                                        THREEWORDINLINE(0x303C, 0x000C, 0xABF2);
  250.  
  251. EXTERN_API( OSErr )
  252. SetDebuggerNotificationProcs    (DebuggerNewThreadProcPtr  notifyNewThread,
  253.                                  DebuggerDisposeThreadProcPtr  notifyDisposeThread,
  254.                                  DebuggerThreadSchedulerProcPtr  notifyThreadScheduler)        THREEWORDINLINE(0x303C, 0x060D, 0xABF2);
  255.  
  256. EXTERN_API( OSErr )
  257. GetThreadCurrentTaskRef            (ThreadTaskRef *        threadTRef)                            THREEWORDINLINE(0x303C, 0x020E, 0xABF2);
  258.  
  259. EXTERN_API( OSErr )
  260. GetThreadStateGivenTaskRef        (ThreadTaskRef             threadTRef,
  261.                                  ThreadID                 threadToGet,
  262.                                  ThreadState *            threadState)                        THREEWORDINLINE(0x303C, 0x060F, 0xABF2);
  263.  
  264. EXTERN_API( OSErr )
  265. SetThreadReadyGivenTaskRef        (ThreadTaskRef             threadTRef,
  266.                                  ThreadID                 threadToSet)                        THREEWORDINLINE(0x303C, 0x0410, 0xABF2);
  267.  
  268.  
  269. #if PRAGMA_STRUCT_ALIGN
  270.     #pragma options align=reset
  271. #elif PRAGMA_STRUCT_PACKPUSH
  272.     #pragma pack(pop)
  273. #elif PRAGMA_STRUCT_PACK
  274.     #pragma pack()
  275. #endif
  276.  
  277. #ifdef PRAGMA_IMPORT_OFF
  278. #pragma import off
  279. #elif PRAGMA_IMPORT
  280. #pragma import reset
  281. #endif
  282.  
  283. #ifdef __cplusplus
  284. }
  285. #endif
  286.  
  287. #endif /* __THREADS__ */
  288.  
  289.